package com.gitee.wsl.collections.map.api


/**
 * Defines a map that holds a set of values against each key.
 *
 *
 * A `SetValuedMap` is a Map with slightly different semantics:
 *
 *
 *  * Putting a value into the map will add the value to a [Set] at that key.
 *  * Getting a value will return a [Set], holding all the values put to that key.
 *
 *
 * @param <K> the type of the keys in this map
 * @param <V> the type of the values in this map
 * @since 4.1
</V></K> */
interface SetValuedMap<K, V> : MultiValuedMap<K, V> {
    /**
     * Gets the set of values associated with the specified key.
     *
     *
     * Implementations typically return an empty `Set` if no values
     * have been mapped to the key.
     *
     *
     * @param key  the key to retrieve
     * @return the `Set` of values, implementations should return an
     * empty `Set` for no mapping
     * @throws NullPointerException if the key is null and null keys are invalid
     */
    override fun get(key: K): Set<V>

    /**
     * Removes all values associated with the specified key.
     *
     *
     * The returned set *may* be modifiable, but updates will not be
     * propagated to this set-valued map. In case no mapping was stored for the
     * specified key, an empty, unmodifiable set will be returned.
     *
     *
     * @param key  the key to remove values from
     * @return the `Set` of values removed, implementations should
     * return null for no mapping found, but may return an empty collection
     * @throws UnsupportedOperationException if the map is unmodifiable
     * @throws NullPointerException if the key is null and null keys are invalid
     */
    override fun remove(key: K): Set<V>
}
